FormSuite for Invoices 1 for .Net - User Guide > How To > Perform Advanced Operations > Template Provider |
A template provider is a class that implements the ITemplateProvider.
This provider performs the methods associated with getting and saving templates for the user application. These methods are:
GetTemplateIds | Get a list of currently saved template identifiers. |
GetTemplate | Get a template associated with a specific template identifier. |
GetTemplateImage | Get a template image associated with a specific template identifier. |
SaveTemplate | Save a template with a given identifier. |
SaveTemplateImage | Save a template image with a given identifier. |
SaveTemplateWithImage | Save a template and image with a given identifier. |
CreateTemplateId | Create a new template identifier. This identifier will be used for saving a new template and template image. |
The template provider is called at two different times during processing:
A file based template provider is included with the API, see FileTemplateProvider.
Setting the template provider into the processor class is done as follows:
Example |
Copy Code |
---|---|
// Setup the template provider ITemplateProvider templateProvider = new TemplateProvider("Templates"); invoiceProcessor.TemplateProvider = templateProvider; |
An example of a file based implementation of a template provider is provided below.
Example |
Copy Code |
---|---|
/// <summary> /// Implement an ITemplateProvider that uses the file system. /// The templates will be read/written from the [templateRooDirectory]\[Company Name]\[Vendor Name] /// Template are Serialized/Deserialized using DataContractSerialization. /// Note: The template Id is the file name without a file extension or path. /// </summary> public class TemplateProvider : ITemplateProvider { /// <summary> /// Root path to the templates /// </summary> private string templateRootDirectory; /// <summary> /// Extension added to the template file /// </summary> private string templateExtension = ".template"; /// <summary> /// Extension added to the template reference image /// </summary> private string templateImageExtension = ".tImage"; /// <summary> /// Create an instance of the template provider with the given directory. /// </summary> /// <param name="templateRootDirectory"></param> public TemplateProvider(string templateRootDirectory) { this.templateRootDirectory = templateRootDirectory; // Create the directory if needed if (System.IO.Directory.Exists(templateRootDirectory) == false) { System.IO.Directory.CreateDirectory(templateRootDirectory); } } /// <summary> /// Build a path to the template files for a given company and vendor /// </summary> /// <param name="company">Company data associated with the templates</param> /// <param name="vendor">Vendor data associated with the templates</param> /// <returns>A path that combines the root, comapany name and vendor name</returns> private string BuildTemplateDirectoryPath(ICompanyData company, IVendor vendor) { string path = templateRootDirectory; if (company != null && string.IsNullOrWhiteSpace(company.CompanyName) == false) { path += path + System.IO.Path.DirectorySeparatorChar + company.CompanyName; } else { path += path + System.IO.Path.DirectorySeparatorChar + "UnknownCompany"; } if (vendor != null && string.IsNullOrWhiteSpace(vendor.Name) == false) { path += path + System.IO.Path.DirectorySeparatorChar + vendor.Name; } else { path += path + System.IO.Path.DirectorySeparatorChar + "UnknownVendor"; } return path; } /// <summary> /// Build a file path to a template file /// </summary> /// <param name="company">Company data associated with the template</param> /// <param name="vendor">Vendor data assoicated with the template </param> /// <param name="templateFile">Template file name, with extension</param> /// <returns>Path to the template file.</returns> private string BuildTemplateFilePath(ICompanyData company, IVendor vendor, string templateFile) { return BuildTemplateDirectoryPath(company, vendor)+System.IO.Path.DirectorySeparatorChar+templateFile; } /// <summary> /// Check if the path exists, if not create it /// </summary> /// <param name="path">Path to create</param> private static void CheckAndCreateDirectory(string path) { if (string.IsNullOrEmpty(path) == false && System.IO.Directory.Exists(path) == false) { System.IO.Directory.CreateDirectory(path); } } /// <summary> /// Create a unique template Id for a template. This is call when a new template is to be created. /// This implementation creates a template id using a new guid. /// </summary> /// <param name="company">Company data assoicated with the template.</param> /// <param name="vendor">Vendor data associated with the template.</param> /// <returns>A unique identifer for a template</returns> public string CreateUniqueTemplateId(ICompanyData company, IVendor vendor) { // Return a guid as a template id return Guid.NewGuid().ToString(); } /// <summary> /// Get a template given a template Id /// </summary> /// <param name="company">Company associated with templateId</param> /// <param name="vendor">Vendor associated with templateId</param> /// <param name="templateId">Id of template to retrieve</param> /// <returns>Retrieved template; null if none found</returns> public TemplatePage GetTemplate(ICompanyData company, IVendor vendor, string templateId) { TemplatePage templatePage = null; string filePath = BuildTemplateFilePath(company, vendor, templateId + templateExtension); if (System.IO.File.Exists(filePath)) { DataContractSerializer serializer = new DataContractSerializer(typeof(TemplatePage)); using (System.IO.FileStream stream = new System.IO.FileStream(filePath, System.IO.FileMode.Open, System.IO.FileAccess.Read)) { templatePage = (TemplatePage)serializer.ReadObject(stream); } } return templatePage; } /// <summary> /// Get Ids of templates matching a given company and vendor /// </summary> /// <param name="company">Company associated with templateId</param> /// <param name="vendor">Vendor associated with templateId</param> /// <returns>Ids of matched templates</returns> public List<string> GetTemplateIds(ICompanyData company, IVendor vendor) { List<string> templateIds = new List<string>(); string templateDirectoryPath = BuildTemplateDirectoryPath(company, vendor); if (System.IO.Directory.Exists(templateDirectoryPath)) { System.IO.DirectoryInfo dirInfo = new System.IO.DirectoryInfo(templateDirectoryPath); if (dirInfo != null) { System.IO.FileInfo[] files = dirInfo.GetFiles("*" + templateExtension); foreach (var file in files) { templateIds.Add(System.IO.Path.GetFileNameWithoutExtension(file.Name)); } } } return templateIds; } /// <summary> /// Get template image given a template Id /// </summary> /// <param name="company">Company associated with templateId</param> /// <param name="vendor">Vendor associated with templateId</param> /// <param name="templateId">Id of template associated with image</param> /// <returns>Stream for retrieved image; null if none found</returns> public System.IO.Stream GetTemplateImage(ICompanyData company, IVendor vendor, string templateId) { string templateImagePath = BuildTemplateFilePath(company, vendor, templateId + templateImageExtension); if (System.IO.File.Exists(templateImagePath)) { return new System.IO.FileStream(templateImagePath, System.IO.FileMode.Open, System.IO.FileAccess.Read); } else { return null; } } /// <summary> /// Get template image given a template Id /// </summary> /// <param name="company">Company associated with templateId</param> /// <param name="vendor">Vendor associated with templateId</param> /// <param name="templateId">Id of template associated with image</param> /// <returns>Stream for retrieved image; null if none found</returns> public void SaveTemplate(ICompanyData company, IVendor vendor, TemplatePage pageTemplate) { if (pageTemplate != null) { if ( string.IsNullOrWhiteSpace(pageTemplate.TemplateId) == true) { pageTemplate.TemplateId = CreateUniqueTemplateId(company, vendor); } CheckAndCreateDirectory(BuildTemplateDirectoryPath(company, vendor)); string templatePath = BuildTemplateFilePath(company, vendor, pageTemplate.TemplateId); DataContractSerializer serializer = new DataContractSerializer(typeof(TemplatePage)); using (System.IO.FileStream fs = new System.IO.FileStream(templatePath, System.IO.FileMode.Create, System.IO.FileAccess.Write)) { serializer.WriteObject(fs, pageTemplate); } } } /// <summary> /// Save a template /// </summary> /// <param name="company">Company template is associated with</param> /// <param name="vendor">Vendor template is associated with</param> /// <param name="pageTemplate">Page template</param> public void SaveTemplateImage(ICompanyData company, IVendor vendor, string templateId, System.IO.Stream imageStream) { CheckAndCreateDirectory(BuildTemplateDirectoryPath(company, vendor)); string templateImagePath = BuildTemplateFilePath(company, vendor, templateId + templateImageExtension); using (var file = new System.IO.FileStream(templateImagePath, System.IO.FileMode.Create, System.IO.FileAccess.Write)) { file.Position = 0; imageStream.Position = 0; imageStream.CopyTo(file); } } /// <summary> /// Save a template image /// </summary> /// <param name="company">Company associated with templateId</param> /// <param name="vendor">Vendor associated with templateId</param> /// <param name="templateId">Id of template associated with image being saved</param> /// <param name="imageStream">Stream to save with</param> public void SaveTemplateWithImage(ICompanyData company, IVendor vendor, TemplatePage pageTemplate, System.IO.Stream imageStream) { SaveTemplate(company, vendor, pageTemplate); SaveTemplateImage(company,vendor, pageTemplate.TemplateId, imageStream); } } |